home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / SICE-DOC.ZIP / DOC-TXT.ZIP / CHAP3 < prev    next >
Text File  |  1992-05-24  |  40KB  |  1,145 lines
  1.   CHAPTER 3
  2.  
  3.  Debugging In 30 Minutes
  4.    3.1 Introduction
  5.    3.2 Popping Up the Window
  6.    3.3 Returning From the Window
  7.    3.4 Changing the Window Size
  8.    3.5 Moving the Window
  9.    3.6 Line Editing Keystrokes
  10.    3.7 Interactive Status Line
  11.    3.8 Command Syntax
  12.    3.8.1 Specifying Memory Addresses
  13.    3.9 Function Keys
  14.    3.10 Help
  15.    3.11 Tutorial
  16.  
  17.       15
  18.  
  19.  3.1 Introduction
  20.  
  21. All interaction with Soft-ICE takes place through a window that can be
  22. popped up at any time. All Soft-ICE commands fit in a small window, but
  23. the window can be enlarged to full screen. You will typically use the
  24. small window when using Soft-ICE as an assistant to another debugger, and
  25. the large window when using Soft-ICE in stand-alone mode.
  26.  
  27. The window initially comes up in full screen mode if you are using the
  28. Soft-ICE configuration file (S-ICE DAT) that was included on the
  29. distribution diskette.
  30.  
  31.  3.2 Popping Up the Window
  32.  
  33. You can bring up the window at any time after installing Soft-ICE. You
  34. initially bring up Soft-ICE by pressing the CTRL and D keys. However, this
  35. sequence can be changed by using the ALTKEY command (see section 5.8).
  36.  
  37.  3.3 Returning From the Window
  38.  
  39. Return to the original display by using the X command or the key sequence
  40. that you used to invoke Soft-ICE. Any break points that you set while
  41. working in Soft-ICE will be armed at this point.
  42.  
  43.  3.4 Changing the Window Size
  44.  
  45. You can modify both the width and the height of the Soft-ICE window.
  46. Changing the window size is particularly useful in stand-alone mode when
  47. you are displaying code memory.
  48.  
  49.  16
  50.  
  51.  The window height can vary from 8 to 25 lines tall. To change the window
  52. height, use the following key sequences:
  53.     
  54.     ALT  -- makes the window taller
  55.     ALT  -- makes the window shorter
  56.  
  57. To change the window width, use the WIN command (see section 5.9).
  58. Entering WIN with no parameters toggles between the following two modes:
  59.  
  60.    WIDE mode -- full screen width
  61.    NARROW mode -- 46 characters wide
  62.  
  63. Some commands (i.e., D, E, R, U) take advantage of the extra width by
  64. displaying more information when the window is in wide mode.
  65.  
  66.  3.5 Moving the Window
  67.  
  68. The Soft-ICE window is movable and can be positioned anywhere on the
  69. screen. This is particularly useful when the window is in narrow mode.
  70. Move the window anytime you need to view information on the screen behind
  71. the window. The following key sequences move the window:
  72.  
  73.     CTRL  -- moves the window one row up
  74.     CTRL  -- moves the window one row down
  75.     CTRL  -- moves the window one column right
  76.     CTRL  -- moves the window one column left
  77.  
  78. 3.6 Line Editing Keystrokes
  79.  
  80. Soft-ICE's easy-to-use line editor allows you to recall and edit previous
  81. commands. The line editor functions are similar to those of the popular
  82. CED line editor. The
  83.  
  84.       17
  85.  
  86.  following key sequences help you edit commands in the command window:
  87.             -- moves the cursor to the right
  88.            -- moves the cursor to the left
  89.     INS     -- toggles insert mode
  90.     DEL     -- deletes the current character
  91.     HOME    -- moves the cursor to start of the line
  92.     END     -- moves the cursor to the end of the line
  93.            -- displays the previous command
  94.            -- displays the next command
  95.     SHIFT   -- scroll one line up in display
  96.     SHIFT   -- scroll one line down in display
  97.     PAGE UP -- scroll one page up in display
  98.     PAGE DN -- scroll one page down in display
  99.     BKSP    -- deletes the previous character
  100.     ESC     -- cancels the current command
  101.  
  102. There are special key assignments when the cursor is in the data window or
  103. the code window. These are described in the sections for the E and EC
  104. command respectively. One special assignment of note is the SHIFT  and
  105. Shift  keys while the cursor is in the code window. These keys are re-
  106. assigned so they have the functions that  and  normally have. This way
  107. you can recall previous commands while the cursor is in the code window.
  108.  
  109.  3.7 Interactive Status Line
  110.  
  111. A status line at the bottom of the window provides interactive help with
  112. command syntax.
  113.  
  114.       18
  115.  
  116.  3.8 Command Syntax
  117.  
  118. Soft-ICE is a command-driven debugging tool. To interact with Soft-ICE,
  119. you enter commands, which can optionally be modified by parameters.
  120.  
  121. All commands are text strings that are one to six characters in length and
  122. are case insensitive. AlI parameters are either ASCII strings or
  123. expressions.
  124.  
  125. Expressions are typically numbers, but can also be combinations of numbers
  126. and operators (e.g., + - /*). All numbers are displayed in hexadecimal
  127. format. Byte parameters are 2 digits long, word parameters are 4, and
  128. double word parameters are 2 word parameters separated by a colon (:).
  129. Here are some examples of parameters:
  130.  
  131.     12 -- byte parameter
  132.     10FF -- word parameter
  133.     E000:0100 -- double word parameter
  134.  
  135.  
  136. Registers can be used in place of bytes or words in an expression. For
  137. example, the command 'U CS:IP-10' will start unassembling instructions ten
  138. bytes before the current instruction pointer address. The following
  139. register name may be used in an expression:
  140.  
  141.    AL, AH, AX, BL, BH, BX, CL, CH, CX, DL, DH,
  142.    DX, DI, SI, BP, SP, IP, CS, DS, ES, SS, or FL
  143.  
  144.  3.8.1 Specifying Memory Addresses
  145.  
  146. Many Soft-ICE commands require memory addresses as parameters. A memory
  147. address is a value that is made of two 16-bit words, separated by a colon.
  148. The first word is the segment address, and the second word is the segment
  149. offset.
  150.  
  151.        19 
  152.  
  153. Public symbols can be used in place of an address in any Soft-ICE command.
  154. The public symbols must have been loaded with the Soft-ICE program loader
  155. (LDR.EXE). See chapter 7 (Symbols and Source) for a complete description
  156. of using public symbols.
  157.  
  158. The Soft-ICE expression evaluator recognizes several special characters in
  159. conjunction with addresses. These special characters are:
  160.  
  161.     $ -- Current CS:IP.
  162.     @address -- Double Word Indirection
  163.     .number -- Source Line Number
  164.  
  165. The $ character can be used in place of CS:IP when typing the address of
  166. the current instruction pointer.
  167.  
  168. The @ character allows you to refer to the double word pointed to by the
  169. address. You can have multiple levels of @'s.
  170.  
  171. If the . character precedes an address, the address will be interpreted as
  172. a source line number in the current file, rather than an actual address.
  173. This is only valid when source files are loaded. The address is
  174. interpreted as a decimal number in this case.
  175.  
  176. Examples:
  177.    U.1234
  178.     This command starts unassembling instructions at
  179.     source line 1234 decimal.
  180.  
  181.     U $-10
  182.     This command unassembles instructions starting 10
  183.     bytes prior to the current instruction pointer.
  184.  
  185.       20
  186.  
  187.     G @SS:SP
  188.     Assume you are at the first instruction of an interrupt
  189.     routine. Entering this command will set a temporary
  190.     break point at the return address on the stack and skip
  191.     the interrupt routine.
  192.  
  193.  3.9 Function Keys
  194.  
  195. Function keys can be assigned to any command string that can be typed into
  196. Soft-ICE. Function keys can be assigned from the command line or pre-
  197. initialized through the Soft-ICE definition file S-ICE.DAT.
  198.  
  199. The default S-ICE.DAT that comes on the Soft-ICE distribution diskette has
  200. definitions for all 12 function keys. You can change any of these
  201. definitions at any time. They are intended as examples, but they are
  202. designed to make easy for users of Microsoft's CodeView, Thee default
  203. assignments are:
  204.  
  205.     F1 -- Displays general help (H;)
  206.     F2 -- Toggles the register window ( ^WR;)
  207.     F3 -- Changes current source mode ( ^SRC;)
  208.     F4 -- Restores screen ( ^RS;)
  209.     F5 -- Returns to your program ( ^X;)
  210.     F6 -- Toggles cursor between command window 
  211.              code window ( ^EC;)
  212.     F7 -- Goes to current cursor line ( ^HERE;)
  213.     F8 -- Single steps ( ^T;)
  214.     F9 -- Sets break point at current cursor line ( ^BPX;)
  215.  
  216.       21
  217.  
  218.  
  219.     F10 -- Program steps ( ^P;)
  220.     F11 -- Go to return address (large model)
  221.               ( ^G@SS:SP;)
  222.     F12 -- Displays Soft-ICE version number ( ^VER;)
  223.  
  224.  A caret ( ^ ) preceding a command makes it invisible, a semi-colon (;)
  225. following a command represents a carriage return. You can display the
  226. current function key assignments by entering the command:
  227.  
  228.  FKEY
  229.  
  230. To use a function key simply press the function key instead of entering
  231. the command. To program function keys see section 5.8 for a description of
  232. the FKEY command, or chapter 6 for a description of pre-initializing
  233. function keys in S-ICE.DAT.
  234.  
  235.  3.10 Help
  236.  
  237. The help command displays a short description, a syntax expression, and an
  238. example of each command. To display help information, enter:
  239.  
  240.     ? or H -- displays short descriptions of all
  241.                       commands and operators
  242.     ? command or
  243.     H command -- displays more detailed information on
  244.                       the specified command, syntax, and an
  245.                       example
  246.     ? expression or
  247.     H expression -- displays the value of the expression in
  248.                       hexadecimal, decimal and ASCII
  249.  
  250.       22
  251.  
  252.  3.11 Tutorial
  253.  
  254. The following tutorial demonstrates a few of the features Soft-ICE and
  255. gives you the opportunity to try using Soft-ICE. Soft-ICE can be used in
  256. conjunction with another debugger or as a stand-alone debugger. The
  257. tutorial demonstrates using Soft-ICE as an assistant to the DOS debugger,
  258. DEBUG, and then shows how Soft-ICE can be used as a stand-alone debugger
  259. with source and symbols loaded. DEBUG can be found on the PCDOS or MSDOS
  260. system diskette. If you do not have DEBUG, you can use another debugger in
  261. its place, or Soft-ICE can be used as a stand-alone debugger.
  262.  
  263. Users who need to use Soft-ICE for a reverse engineering project, or for
  264. debugging DOS loadable device drivers or Terminate and Stay Resident
  265. programs should go through this tutorial too. Even though examples of
  266. these types of programs are not demonstrated directly, you will get an
  267. overview of debugging with Soft-ICE. It is recommended that you experiment
  268. with Soft-ICE and your particular environment before beginning a real
  269. project.
  270.  
  271. A short assembly language program with a subtle flaw is used to
  272. demonstrate hardware-style break points. The sample program has been kept
  273. intentionally short and to-the-point for those not very familiar with
  274. assembly language. The tutorial is designed to give you a peek at Soft-ICE
  275. features. Feel free to experiment on your own after going through the
  276. tutorial.
  277.  
  278. Since Soft-ICE is very flexible, it allows you to load in the way that is
  279. best for your system. Go through the installation procedures in section 
  280. 2.2 before continuing with the tutorial.
  281.  
  282. If you do not have extended memory on your system, you must load Soft-ICE
  283. from the command line. When loading Soft-ICE from the command line you can
  284. not load symbols or source files. In this case you must improvise in the
  285. last
  286.  
  287.       23
  288.  
  289.  section of the tutorial where Soft-ICE is used as a stand-alone debugger.
  290.  
  291. Soft-ICE can be loaded from the DOS prompt or loaded as a device driver in
  292. CONFIG.SYS. For the purpose of this tutorial you should install Soft-ICE
  293. in CONFIG.SYS with at least 50K of extended memory reserved for symbols
  294. and source files. Soft-ICE should be the first device driver installed in
  295. CONFIG.SYS. The device installation line should look like:
  296.  
  297.       DEVICE = drive: path\S -ICE.EXE /SYM 50
  298.  
  299. The /SYM 50 parameter instructs Soft-ICE to reserve 50 kilobytes of
  300. extended memory for symbols and source file This is not enough to solve
  301. most real world problems, but will work for our sample program.
  302.  
  303. You must re-boot your system after placing this line in CONFIG.SYS.
  304.  
  305. When you re-boot your system Soft-ICE displays a copyright notice, a
  306. registration number, the name of the person who owns this copy of Soft-
  307. ICE, and the amount a extended memory reserved for each Soft-ICE
  308. component. On a system with 384K of extended memory the initial screen
  309. looks like:
  310.  
  311.             Soft-ICE Your Name Your Company Name Registration # SInnnnnn
  312. Copr. (C) Nu-Mega Technologies 1987-1989 All Rights Reserved Soft-ICE
  313. Version 2.00 Soft-ICE is loaded from 00132000H up to 00160000H. 50K of
  314. symbol space reserved. 10K of back trace space reserved. 200 K of extended
  315. memory available.
  316.  
  317.       24
  318.  
  319.  The "Soft-ICE is loaded ..." message tells you the exact area of memory
  320. that Soft-ICE and its components are occupying. If you are on a Compaq or
  321. Compaq clone and have included the word COMPAQ in your S-ICE.DAT file you
  322. would also see a message saying "Using high memory from XXXXXXXX to
  323. 00FE0000H".
  324.  
  325. The next line tells you how much symbol space has been reserved. This
  326. space is used for both symbols and source files.
  327.  
  328. The next line tells you how much memory has been reserved for back trace
  329. history. This amount defaults to 10K. This memory area is used by the SNAP
  330. command and the BPR command with the T or TW options.
  331.  
  332. The last line tells you how much memory is left for regular extended
  333. memory. This memory can be used by other programs, such as HIMEM,
  334. SMARTDRIVE, VDISK, etc.
  335.  
  336. Change directories to the hard drive directory where you loaded all the
  337. files from your distribution diskette. Remember, this directory must be
  338. accessible from your alternate path list.
  339.  
  340. Before we get into heavy debugging, let's bring the Soft-ICE window up and
  341. give it a test drive.
  342.     Clear the screen by entering:
  343.       CLS
  344.     Bring up the Soft-ICE window by pressing:
  345.        CTRL D
  346.  
  347. The Soft-ICE window is now on the screen. If you have file S-ICE.DAT
  348. accessible from your path then the Soft-ICE window will occupy the entire
  349. screen. It will be divided into four sections. From top to bottom, these
  350. sections are the register window, the data window, the code
  351.  
  352.       25
  353.  
  354. window, and the command window. If S-ICE.DAT was not found then you will
  355. have a small window in the center of the screen. This also means that
  356. other components needed for the tutorial have not been loaded.
  357.  
  358. If the small window is visible you should:
  359.     1. Exit from Soft-ICE by entering X.
  360.     2. Unload Soft-ICE by entering S-ICE /U.
  361.     3. Copy the file S-ICE.DAT from the distribution
  362.          diskette to a directory accessible from your current
  363.          path.
  364.     4. Restart the demo.
  365.  
  366. We will now switch to the small window. The small window is very
  367. convenient for using Soft-ICE as an assistant to another debugger.
  368.  
  369.     Enter:
  370.       WIN
  371.  
  372. This will make a small command window in the center of the screen. Several
  373. Soft-ICE commands are visible on this screen. These are remnants of the
  374. initialization string in S-ICE.DAT that originally set up Soft-ICE in the
  375. full screen mode.
  376.  
  377. You will notice a prompt symbol (:) and a status line at the bottom of the
  378. window.
  379.  
  380. The Soft-ICE window can be moved around on the screen, and the window size
  381. can be adjusted.
  382.  
  383.    Move the window around the screen by pressing:
  384.         CTRL  -- moves the window up one row
  385.         CTRL  -- moves the window down one row
  386.         CTRL  -- moves the window one column left
  387.         CTRL  -- moves the window one column right
  388.  
  389.       26
  390.  
  391.    Change the window size so that it fills the whole screen
  392.    by entering:
  393.       WIN
  394.  
  395. You will notice that the original screen is back.
  396.  
  397.    Change back to the small window by entering WIN
  398.    again.
  399.    Make the window taller or shorter by pressing:
  400.  
  401.       ALT  -- makes the window taller
  402.       ALT  -- makes the window shorter
  403.  
  404. Now try what comes naturally when you're in front of a new program and you
  405. don't have the foggiest notion of what to do next -- ask for help.
  406.     
  407. Get a help display by entering:
  408.         ?
  409.  
  410. Notice how the display stops and waits for a keystroke before scrolling
  411. any information off the screen. Look at the status line at the bottom of
  412. the window. The status line displays the instructions: "Any Key To
  413. Continue, ESC to Cancel ". Now press any key to continue displaying more
  414. the help information. Continue pressing the key until the prompt (: )
  415. reappears.
  416.  
  417.     Scroll back through the help information by pressing
  418.       SHIFT 
  419.  
  420. Previously displayed information in the command window can be scrolled
  421. with the shift up, shift down, page up and page down keys. Try a variety
  422. of these keys to scroll through the help information.
  423.  
  424.       27 
  425.  
  426. The Soft-ICE help facility gives you an overview of each command. If you
  427. enter a question mark (?) followed by a command name, you see a display
  428. showing the command syntax, a short description of the command, and an
  429. example.
  430.  
  431.    Try experimenting with help by entering commands in
  432.    this format:
  433.       ? command
  434.    For example,
  435.       ? ALTKEY
  436.  
  437. Pay attention to the status line prompts on the bottom line of the screen
  438. if you get confused.
  439.  
  440. The help command also allows you to evaluate hexadecimal expressions.
  441.  
  442.     For example, enter:
  443.       ? 10*2+42
  444.  
  445.     The resulting display shows you the value of the
  446.     expression, first in hexadecimal, then decimal, then in
  447.     ASCII representation:
  448.       0062 00098 "b"
  449.  
  450. We brought up the window with the CTRL D key sequence. That's all right
  451. for some, but you may prefer to use another key sequence.
  452.  
  453. We are now going to enter a command to change the key sequence required to
  454. bring up the window. We'll do this one step at a time, so you can get used
  455. to the status line at the bottom of the window.
  456.  
  457.       28
  458.  
  459.    Type the letter 'A'. The status line displays a list of all
  460.    the commands starting with the letter 'A'. Finish
  461.    typing the word 'ALTKEY'. The status line now
  462.    displays a short description of the /ALTKEY command
  463.    Press the space bar. The status line now shows the
  464.    required syntax for the /ALTKEY command. Type the
  465.    letters 'ALT D' then press ENTER to enter the entire
  466.    command:
  467.  
  468.      ALTKEY ALTD
  469.  
  470. You just changed the window pop up key sequence to ALT D. From now on, you
  471. must press the ALT D key sequence to pop up the window. This is assumed
  472. throughout the remainder of the tutorial.
  473. Now let's test the previous command.
  474.  
  475.     To exit from the window, press:
  476.        ALT D
  477.  
  478. The Soft-ICE window just disappeared.
  479.     To return to the Soft-ICE window, release the ALT
  480.     key, then press:
  481.        ALT D
  482.  
  483. The window returned.
  484.     To see some previous commands, press:
  485.     the  key a few times.
  486.  
  487.  
  488.       29  
  489.  
  490. Notice that Soft-ICE remembers commands that have been entered. Try
  491. editing one just for fun. Some of the editing keys are:
  492.  
  493.          INS -- Toggles insert mode on or off
  494.          DEL -- Deletes one character
  495.          HOME -- Moves the cursor to start of line
  496.          END -- Moves the cursor to end of line
  497.               -- Moves the cursor one column to the right
  498.               -- Moves the cursor one column to the left
  499.  
  500. When insert mode is on, notice that the cursor is in a block shape.
  501.  
  502. Now that you are somewhat familiar with the environment let's try some
  503. more commands.
  504.  
  505.     Erase the command you were editing by pressing the
  506.     HOME key, then pressing the DEL key until the
  507.     command is gone.
  508.  
  509.     Enter:
  510.            WR
  511.  
  512. The WR command makes the register window visible. The register window
  513. displays the contents of the 8086 registers. Notice that the register
  514. values reflect the location where the code was executing when you invoked
  515. Soft-ICE.
  516.  
  517. The WR command is assigned to the function key F2 in the Soft-ICE
  518. initialization file S-ICE.DAT.
  519.  
  520.     Press the F2 key several times and you will see the
  521.     register window toggle on and off. Leave the register
  522.     window visible.
  523.  
  524.       30
  525.  
  526.    Extend the vertical size of the Soft-ICE window by
  527.    holding down the ALT and the  until the window is
  528.    the entire length of the screen.
  529.     Notice the values of the CS and IP registers in the
  530.     register window, then enter:
  531.  
  532.        MAP
  533.  
  534. The MAP command displays a system memory map. The area of the current
  535. instruction pointer (CS:IP) is highlighted. If you have a complex memory
  536. map you may have to press a key a few times until the until the prompt
  537. reappears.
  538.  
  539.     Now try the following sequence a few times, noticing
  540.     the (CS:IP) registers in the register window.
  541.       ALT D
  542.       Release ALT and D
  543.       ALT D
  544.  
  545. Each time you bring the Soft-ICE window back up you will notice that the
  546. CS and IP registers have changed. When CS and IP change you can enter the
  547. MAP command again to see if the instruction pointer now points to a
  548. different area.
  549.  
  550. This little exercise demonstrates that Soft-ICE is a system level debugger
  551. that pops up wherever the instruction pointer happens to be when you press
  552. the Soft-ICE hot key sequence. The instruction pointer is continuously
  553. changing because there is a lot of activity happening behind the scenes
  554. even when you are at the DOS prompt, such as timer interrupts, DOS device
  555. driver polling, DOS busy waiting other interrupts, etc.
  556.  
  557.       31
  558.  
  559.     Press the F12 function key.
  560.  
  561. The F12 function key defaults to be assigned to the Soft-ICE VER command.
  562. It displays the Soft-ICE copyright message and the version number.
  563. We will now assign the F12 function key to the Soft-ICE RS command.
  564.  
  565.     Enter:
  566.        RS
  567.  
  568. This will temporarily show the program screen without the Soft-ICE window.
  569.     Press the space bar to get back to get back the Soft-ICE
  570.     window.
  571.     Enter:
  572.       FKEY F12 RS;
  573.  
  574. This assigns the RS command to the F12 key. The semi-colon represents the
  575. ENTER key.
  576.     Press the F12 key.
  577.  
  578. Repeat this a few times to toggle between the Soft-ICE window and the
  579. program screen. Now make sure the Soft-ICE window is displayed, by
  580. pressing the F12 key if necessary. You will notice RS displayed several
  581. times in the window. There is one occurrence for each time you pressed the
  582. F12 key to show the program screen.
  583.  
  584.     Clear the Soft-ICE window by entering:
  585.        CLS
  586.       32
  587.  
  588.     Enter:
  589.       FKEY F12 ^RS;
  590.  
  591. The ^ symbol is a shifted 6. This assigns the RS command to the F12 key,
  592. but makes it an invisible command.
  593.  
  594.     Press the F12 key several times. Notice that the RS
  595.     command no longer displays in the Soft-ICE window.
  596.  
  597.  
  598. You can also assign a sequence of Soft-ICE commands to a function key.
  599. Remember to place a carriage return between each command.
  600. Now let's prepare to use Soft-ICE as an assistant to the MSDOS DEBUG
  601. utility.
  602.  
  603.     Get rid of the register window by pressing the F2.
  604.     then shrink the window size down to about 6 lines by
  605.     Using ALT .
  606.     Enter:
  607.       ACTION INT3
  608.  
  609. This command tells Soft-ICE to generate interrupt 3's when break point
  610. conditions are met. That's how Soft-ICE will communicate with DEBUG. The
  611. default setting is HERE. ACTION HERE will cause control to return directly
  612. to Soft-ICE. Use ACTION HERE when using Soft-ICE as a stand-alone
  613. debugger.
  614.  
  615. For those of you not using DEBUG with this tutorial you might have to
  616. improvise now. CODEVIEW works with ACTION set to NMI. Most other debuggers
  617. will work with ACTION set to INT3. If your debugger doesn't, and you need
  618. help improvising, refer to the complete description ACTION (see section
  619. 5.4).
  620.  
  621.       33
  622.  
  623.     To make the Soft-ICE window disappear again, enter:
  624.         X
  625.  
  626. This is an alternative method to exit from Soft-ICE. This especially
  627. useful in function key definitions.
  628.  
  629. Now that you are familiar with some of the basics of using Soft-ICE, let's
  630. learn some details by debugging the sample program (SAMPLE.ASM).
  631.  
  632. SAMPLE.ASM is a simple program written in assembly language by a
  633. programmer named Jed. The program reads a keystroke from DOS and displays
  634. a message telling whether the keystroke was a space.
  635.  
  636.    To run the program SAMPLE, enter:
  637.       SAMPLE
  638.  
  639. Now press the space bar. Press several keys. Jed's program obviously has a
  640. problem! Jed has spent hours studying this source code and is certain
  641. there are no flaws in his logic. However, Jed borrowed some 'helper'
  642. routines from his friend Jake (get_key, is_space?). Jed is somewhat
  643. suspect these routines but he cannot find the bug.
  644.  
  645.       34 
  646.  
  647. The source code for Jed's program looks like this:
  648.  
  649.    Page 55,80
  650.    Title Sample program for Soft-ICE tutorial
  651.  DATA Segment Public 'Data'
  652.  pad       db 12H dup(O)
  653.  char db 0
  654.  answer db 0
  655.  space_msg db 'The Character is a SPACE',0DH,0AH,'$'
  656.  no_space_msg db 'The Character is NOT a'
  657.              db 'SPACE',0DH,0AH,'$'
  658.  DATA Ends
  659.  STACK Segment Stack 'Stack'
  660.    Dw 128 Dup (?)     ;Program stack STACK Ends
  661.  CODE Segment Public 'Code'
  662.  Assume CS:CODE,DS:DATA,ES:Nothing,SS:STACK
  663.  
  664. start:
  665.  
  666.  
  667. ; Set up segments
  668.    mov ax,DATA
  669.    mov es,ax
  670.    mov ds,ax
  671.  
  672. ; Main Program Loop
  673. main,loop:
  674.     call get_key
  675.     call is_space?
  676.     cmp answer,0
  677.     je no,space 
  678. ; It's a space, so display the space message
  679.  
  680.       35
  681.  
  682.    mov ah,9
  683.    mov dx,offset space_msg
  684.    int 21H
  685.    jmp main_loop
  686. ; It's NOT a space, so display the no space message
  687.  
  688. no_space:
  689.    mov ah,9
  690.    mov dx,offset no_space_msg
  691.    int 21H
  692.    jmp main_loop
  693.  
  694. ;----------------------------------------------------------; 
  695. ; JAKE'S ROUTINES 
  696. ;----------------------------------------------------------; 
  697.  
  698. ; Get Key Routine (one of Jake's routines) 
  699. get_key proc
  700.    mov ah,8
  701.    int 21H
  702.    mov char,al
  703.    ret get_key endp
  704.  
  705. ; Check if character is a space (one of Jake's routines)
  706.  
  707. is_space? proc
  708.    cmp char,20H
  709.    jne not_space
  710.    mov answer, 1
  711.    ret not_space:
  712.    mov cs:answer,0
  713.    ret is_space? endp
  714.  
  715. CODE Ends
  716.    Endstart
  717.  
  718.       36 
  719.  
  720. Jed has been using DEBUG but has not been able to pinpoint the problem. As
  721. a recommendation from his nephew Jethro, Jed has purchased Soft-ICE. He
  722. was somewhat reluctant to use it because he had tried a hardware-assisted
  723. debugger but could never get it working quite right. He was willing to try
  724. Soft-ICE because he could continue to use DEBUG -- the only debugger he
  725. really understood.
  726.  
  727.     Press CTRL C to break out of the program.
  728.     Enter the following commands:
  729.       DEBUG drive:\pathname\SAMPLE. EXE
  730.         U
  731.         R
  732.  
  733. In the hours Jed has spent trying to find this elusive bug, he has had the
  734. suspicion that something is overwriting his code in some subtle way. With
  735. Soft-ICE, Jed decides to set a range break point across his code segment.
  736.  
  737.      Press:
  738.        ALT D
  739.  
  740. The Soft-ICE window is back. Move the window (by using
  741. CTRL and the arrow keys) until DEBUG's register
  742. display is visible. It's time to set our first break point.
  743.  
  744.      Enter:
  745.          BPR code-seg:0 code-seg:25 W
  746.  
  747. Code-seg is the value in the CS register as displayed by the
  748. DEBUG R command.
  749.  
  750. The BPR command sets a memory-range break point. The length of Jed's code
  751. segment is 25H bytes, so the memory range specified goes from the
  752. beginning of his code  segment to the end. The W tells Soft-ICE to break
  753. on a write. We want to catch any unexpected writes to Jed's code.
  754.  
  755.       37
  756.  
  757.     Enter:
  758.         BL
  759.  
  760.  
  761. The BL command displays all break points. The display from BL looks
  762. similar to the following display:
  763.  
  764.    0) BPR code-seg:0000 code-seg:0025 W C = 01
  765.  
  766. The 0 is the identifier for this break point. The range and W are
  767. displayed as they were entered, and the count (since none was specified)
  768. defaults to one.
  769.  
  770. Now comes the moment of truth.
  771.    Press ALT D.
  772.  
  773. The window disappears again.
  774.    To run SAMPLE from DEBUG, enter:
  775.         G
  776.     Press the space bar. Ok so far. Now press a non-space
  777.     key.
  778.  
  779. Our break point just woke up DEBUG. The registers and single unassembled
  780. instruction are displayed.
  781.  
  782.     Enter:
  783.        U cs:address
  784.  
  785. Address is the value of the IP register minus 10 hexadecimal. Since DEBUG
  786. is rather primitive, the value of the IP register minus 10 hexadecimal
  787. must be calculated by hand. The instruction pointer is pointing one
  788. instruction past the instruction that caused the break point. By going
  789. back ten hexadecimal instructions, DEBUG should sync up.
  790.  
  791.       38 
  792.  
  793. The instruction at offset 3BH is:
  794.        CS:
  795.        MOV BYTE PTR [13],0
  796.  
  797. Jed says,"There it is! I just knew Jake's helper routines were the
  798. problem! His code segment override instruction is writing a zero byte
  799. right over my code! Who knows what that's doing!"
  800.  
  801.     Enter:
  802.         U 0
  803.  
  804. Location 13H happens to be the offset of a conditional jump instruction.
  805. The relative offset of the conditional jump is being set to zero. If you
  806. are an 8086 guru, you obviously know that the JE will ALWAYS fall through
  807. if the relative offset is zero. What a subtle BUG!
  808.  
  809. Now we will take a quick look at how this problem would be solved using
  810. Soft-ICE as a stand-alone debugger. But first we must exit from debug.
  811.  
  812. Before exiting the debugger, it's always a good idea to disable all the
  813. break points, unless ACTION is set to HERE. If you do not do this, when a
  814. break point occurs and ACTION tries to return to a debugger that is not
  815. loaded, the results are unpredictable. We've changed the ACTION to INT3,
  816. so we have to disable the break point.
  817.  
  818.    To bring up the window, press:
  819.       ALT D
  820.  
  821.     List the break point by entering:
  822.         BL
  823.  
  824.       39 
  825.  
  826. Notice that the break point description line is highlighted. The
  827. highlighted break point is the last break point that occurred.
  828.  
  829.     Notice that the break point number is 0. To disable
  830.     break point zero, enter:
  831.       BD 0
  832.     List the break point again by entering:
  833.         BL
  834.  
  835. The asterisk (*) after the break point number shows that the break point
  836. is disabled.
  837.  
  838.     To clear the break point, enter:
  839.       BC 0
  840.    Enter BL again.
  841.  
  842. Notice that there are no break point lines displayed.
  843.  
  844.    Exit from Soft-ICE, then exit from the debugger, by
  845.    entering:
  846.         X
  847.         Q
  848.  
  849.  The next part of the tutorial demonstrates how Soft-ICE can be used to
  850. find the same problem as a stand-alone debugger. Soft-ICE will be used as
  851. a source level debugger.
  852.  
  853. To prepare Soft-ICE to debug at source level it must have been installed
  854. in your CONFIG.SYS file, and extended memory allocated for symbols and
  855. source files. Soft-ICE can only be used as a source level debugger if you
  856. have extended memory on your system. If you do not have
  857.  
  858.       40 
  859.  
  860. extended memory you may still want to read through the rest of the
  861. tutorial to see the capabilities of Soft-ICE with extended memory. If you
  862. have not loaded S-ICE.EXE in your CONFIG.SYS file with memory reserved for
  863. symbols, do so at this time.
  864.  
  865. To debug the sample program with Soft-ICE as a stand-alone debugger we
  866. must use the Soft-ICE program loader (LDR.EXE). To load the sample
  867. program(SAMPLE.EXE), the symbol file (SAMPLE.SYM) and the source
  868. file(SAMPLE.ASM) enter:
  869.  
  870.       LDR SAMPLE
  871.  
  872. You are now in Soft-ICE with SAMPLE.EXE loaded into memory. Notice that
  873. Soft-ICE occupies the full screen. Soft-ICE switches to its wide mode
  874. whenever a program loaded. The source from SAMPLE.ASM should be visible in
  875. the code window. In addition, the register window and the DATA windows are
  876. visible.
  877.  
  878.     Step through one instruction by pressing F10.
  879.  
  880. Notice that the reverse video bar moves to the next instruction to be
  881. executed after a program step.
  882.  
  883.     Press F6.
  884.  
  885. This places the cursor in the code window.
  886.     Now experiment with the , , pageUp, and
  887.     pageDn keys to move the cursor and scroll the
  888.     source file.
  889.     Move the cursor down to line 42 with the  key.
  890.       
  891.       41
  892.  
  893.     Press F9.
  894. We have just set an execution break point on line 42. The line should be
  895. highlighted, showing you that a break point has been set on it.
  896.  
  897.     Enter:
  898.             BL
  899.  
  900. This shows the break point that we have just set.
  901.    Now press ALT D.
  902.  
  903. This exits Soft-ICE, and causes the sample program to execute until it
  904. encounters the break point on line 42. Soft-ICE should immediately come
  905. back, with the reverse video bar on line 42.
  906.  
  907.     Press F6 again.
  908.  
  909. This will bring the cursor back to the command window. Now enter:
  910.       BC *
  911.  
  912. This will clear all the break points (there should only be one set).
  913.     Now exit from Soft-ICE by pressing ALT D.
  914.  
  915. You are back to the sample program. Type a few keys just to make sure it
  916. is still broken.
  917.    Now pop Soft-ICE back up with ALT D.
  918.  
  919. Since the bug has already occurred, we want to restart the program. Enter:
  920.       EXIT RD
  921.  
  922.       42 
  923.  
  924. This command forces the sample program to exit. The R tells Soft-ICE to
  925. restore the interrupt vectors to the state they were when the sample
  926. program was loaded with LDR. The D tells Soft-ICE to delete any currently
  927. pending break points. The R and the D are not necessary in this case, but
  928. it is good to get in the habit of specifying them when exiting a program
  929. that was loaded with LDR.EXE.
  930.  
  931.    You are now back at the DOS prompt. Reload the
  932.    program by entering:
  933.  
  934.       LDR SAMPLE.EXE
  935.  
  936. Notice the suffix.EXE was specified this time. When the suffix is
  937. specified, Soft-ICE does not attempt to load a symbol file or source file.
  938. In this case the symbol file and source file are already in memory.
  939.  
  940.     Enter:
  941.       SYM
  942.  
  943. This displays the public symbols of the sample program.
  944.     Press Esc to get back to the prompt.
  945.  
  946. We will now set a range break point similar to the one we set while using
  947. Soft-ICE as an assistant to debug. This time we will use symbols to set
  948. the break point. Enter:
  949.  
  950.       BPR START .82 W
  951.  
  952. This will set a range break point in our code segment from the symbol
  953. START to line 82 of the source file.
  954.  
  955.     Enter:
  956.         BL
  957.  
  958. You can verify that the break point has been set properly.
  959.  
  960.       43
  961.  
  962.    Press ALT D.
  963.    Press a non-space key.
  964.  
  965. We're back in Soft-ICE. Notice that the current instruction (the line with
  966. the reverse video bar) is the instruction after the one that caused the
  967. break point.
  968.  
  969.     To see the actual code press the F3 key.
  970.  
  971. This places Soft-ICE in mixed mode. Notice that the reverse video bar
  972. covers 2 lines. This is the actual code line and the source code line of
  973. the current instruction.
  974.  
  975.    Press the F3 key again.
  976.  
  977.  
  978. We are now in code mode. No source lines are visible. The instruction
  979. above the reverse video bar is the instruction that caused the range break
  980. point to go off.
  981.  
  982.    Press the F3 key again to get back to source mode.
  983.  
  984. Now we will fix the bug in the sample program.
  985.    Exit the sample program and go back to the DOS
  986.    prompt by entering:
  987.       EXIT RD
  988.  
  989.     Re-load the sample program by entering:
  990.       LDR SAMPLE. EXE
  991.  
  992.     Set the code window in code mode by pressing the
  993.     F3 key twice.
  994.     Un-assemble at the broken routine by entering:
  995.     U not_space
  996.  
  997.       44 
  998.  
  999. We will now use the Soft-ICE interactive assembler to fix the problem.
  1000.  
  1001.     Enter:
  1002.       A not_space
  1003.  
  1004. Soft-ICE will prompt you with the address.
  1005.     Enter:
  1006.       NOP
  1007.     Press ENTER to exit from the assembler.
  1008.  
  1009. Notice in the code window that there is a NOP instruction in place of the
  1010. CS over-ride at offset 003BH.
  1011.  
  1012.     Press the F3 key to get back to source mode, (the
  1013.     source code of course is not modified).
  1014.    Press ALT D to run the mended sample program.
  1015.  
  1016.     Enter:
  1017.         spaces and some non-spaces
  1018.  
  1019. It works! You fixed the bug!
  1020.     To get out of Jed's program, and return to DOS, press:
  1021.       CTRL C
  1022.  
  1023. Now we're going to demonstrate another feature of Soft-ICE.
  1024.     Enter:
  1025.       LDR SAMPLE.EXE
  1026.  
  1027. This will load the sample program in one more time.
  1028.  
  1029.       45
  1030.  
  1031.     Enter:
  1032.       RIP HANG_EXAMPLE
  1033.  
  1034. The first two displayed instructions are:
  1035.    CLI
  1036.    JMP $
  1037.  
  1038. Notice that the jump instruction jumps to itself. This infinite loop would
  1039. normally hang the system in an unrecoverable fashion.
  1040.  
  1041.     Enter:
  1042.       BREAK ON
  1043.  
  1044. We have just turned on BREAK mode. BREAK mode will cause the system to run
  1045. slightly slower, but will allow Soft-ICE to come up even when the system
  1046. would normal be hung.
  1047.  
  1048.    Exit from Soft-ICE by pressing ALT D.
  1049.    Your system is now hung. For those non-believers, press:
  1050.       CTRL ALT DEL
  1051.  
  1052. Nothing happens! It is definitely hung.
  1053.    Now press ALT D.
  1054.  
  1055. The Soft-ICE window is back!
  1056.    To get out of the infinite loop, enter:
  1057.       EXIT RD
  1058.  
  1059. You are now back at DOS. Try a few directories to get a feel for the
  1060. performance degradation. Many people feel comfortable leaving BREAK ON as
  1061. a configuration default.
  1062.  
  1063.       46
  1064.  
  1065.    Turn BREAK mode off again by entering:
  1066.       ALT D
  1067.       BREAK OFF
  1068.       ALT D
  1069.  
  1070.  Do a few directories to get a comparison of the speed.
  1071. That's it! Have fun! It's time to start experimenting and debugging on
  1072. your own. Browse through the rest of the manual and refer to specific
  1073. sections when necessary.
  1074.  
  1075.       47
  1076.  
  1077.       Blank
  1078.  
  1079.       48
  1080.  
  1081.      SECTION II -- Commands
  1082.  
  1083.  Section II contains syntax listings for each Soft-ICE command, and
  1084. explanations and examples for each command. All numbers are in
  1085. hexadecimal; any number can be an expression using +,-,/,*, or registers.
  1086. All commands are case-insensitive. Words that are in italics the command
  1087. syntax statements must be replaced by an actual value, rather than typing
  1088. in the italicized word.
  1089.  
  1090.  The following notational conventions are used throughout this section:
  1091. [ ] -- Brackets enclose an optional syntax item.
  1092. < > -- Angle brackets enclose a list of items
  1093.                    or choices.
  1094. x | y -- Vertical bars separate alternatives.
  1095.                    Use either item x or item y.
  1096. count -- Count is a byte value that specifies the
  1097.                    number of times break point conditions
  1098.                    must be met before the actual break point
  1099.                    occurs. If no count is specified, the
  1100.                    default value is 1. Each time the
  1101.                    Soft-ICE window is brought up, the
  1102.                    counts are reset to the values originally
  1103.                    specified.
  1104. verb -- Verb is a value that specifies what type
  1105.                    access the break point will apply to. It
  1106.                    can be set to 'R' for reads, 'W' for write
  1107.                    'RW' for reads and writes, or 'X' for
  1108.                    execute.
  1109. address -- Address is a value that is made of two 16-bit
  1110.                    words, separated by a colon. The first
  1111.                    word is the segment address, and the
  1112.  
  1113.       49
  1114.  
  1115.                  second word is the segment offset. The
  1116.                  addresses can be constructed of registers
  1117.                  expressions, and symbols.
  1118.                  Thee address may also contain the special
  1119.                  characters "$", ".", and "@". See section
  1120.                  3-8 (Command Syntax) for a description
  1121.                  of these special characters.
  1122. break-number -- Break-number is an identification number
  1123.                  that identifies the break point to use
  1124.                  when you are manipulating break points
  1125.                  (e.g., editing, deleting, enabling, or
  1126.                  disabling them). The break-number can
  1127.                  be a hexadecimal digit from 0 to F.
  1128. list -- List is a series of break-numbers separated
  1129.                  by commas or spaces.
  1130. mask -- Mask is a bitmask that is represented as:
  1131.                  combination of 1's, 0's, and X's. X's are
  1132.                  don't-care bits.
  1133.  
  1134.    Example:
  1135.  
  1136.    BPIO 21 W EQ M 1XXX XXXX 
  1137.  
  1138.    This command will cause a break point to occur if port
  1139.    21H is written to with the high order bit set.
  1140. GT, LT -- GT and LT are command qualifiers that
  1141.                  unsigned comparisons of values.
  1142.  
  1143.       50
  1144.  
  1145.